用 canvas 把 AI 产出「贴」到你的 Mac 屏幕上 — OpenClaw widget panel 实战

OpenClaw 的 canvas 工具能把一个托管文档/看板直接推到配对 macOS 节点的面板里,让 AI 的产出脱离聊天框、常驻在你眼前。本文讲清它是什么、怎么用、什么场景最值。

它解决什么问题

平时 AI 给你的东西,都困在聊天窗口里:一段代码、一张表、一个待办清单。你问完就划走了,它不会「挂」在你屏幕上陪你干活。

canvas(Canvas)是 OpenClaw 的一个工具,它干一件事:把一个托管文档或 widget 直接呈现到一台配对的 macOS 节点的面板(panel)上。也就是把 AI 的产出「贴」到你自己的 Mac 屏幕上,常驻可见,不用反复翻聊天记录。

这对哪些人有用?

跑长任务时,想实时看到进度卡/看板(而不是每隔几分钟回聊天框翻)。

写代码时,想让 AI 把接口文档/架构图钉在屏幕一角。

做演示/直播时,想让面板自动切到某张图或某个本地 App。

工具长什么样(真实参数,非编造)

canvas 的输入结构(取自本机实际工具定义):

{
  action: "present" | "hide" | "navigate";
  gatewayToken?: string;
  gatewayUrl?: string;
  height?: number;
  node?: string;
  target?: string;
  timeoutMs?: number;   // 整数, >= 1
  url?: string;
  width?: number;
  x?: number;
  y?: number
}

三个动作:

present:显示面板。可以带一个托管文档路径或本地 App scheme;也可以只显示面板本身。

hide:隐藏面板。

navigate:让当前可见的面板跳转到另一个托管文档路径或本地 App scheme。

可选定位参数 x / y / width / height 用来控制面板在屏幕上的位置和大小;node 指定往哪台配对节点推(多台 Mac 时要用);target 用于指定呈现目标。

正常路径:用 show_widget 而不是直接调 canvas

OpenClaw 的设计里,画布的「内容」由 show_widget 负责生成并托管,canvas 只负责面板的显示/隐藏/跳转控制。也就是说:

先用 show_widget 创建一个托管 widget 文档,带上 presentation.target: "node_panel"。它会返回一个能力作用域内的托管路由,形如 /__openclaw__/canvas/documents/...。

再用 canvas 的 present / navigate 把那个路由推到 Mac 面板上。

不要自己编本地文件路径或任意外部 URL——托管文档走的就是上面那个 /__openclaw__/canvas/documents/... 路由,A2UI 内容会渲染在会话看板上,渲染资源从 /__openclaw__/a2ui 加载。

实战踩坑提醒

1. 没配对 Mac 等于没戏。 canvas 面板依赖「配对的 macOS 节点」。如果你的 OpenClaw 没有连过 Mac 节点(nodes 里看不到可用 Mac),canvas 就没法把东西推到屏幕上。先确认节点在线,必要时用 node 参数显式指定。

2. 开关是联动的。 当 plugins.entries.canvas.config.host.enabled 为 false 时,托管 widget 文档、A2UI 渲染资源、节点面板呈现这三者会一起被禁用。别只改其中一项,改了不生效就去看这个总开关。

3. 别和 dashboard 混了。 dashboard 工具管的是「本会话仪表盘」(侧边/分屏的那套 widget 编排),canvas 管的是「推到 Mac 物理面板」。两者走不同呈现通道,作者的场景是「让输出常驻我的屏幕」,选 canvas,不是 dashboard。

4. navigate 比 hide+present 干净。 想换内容时直接用 navigate 跳到新路由,不要先 hide 再 present,少一次面板状态抖动。

一个能直接套用的场景

假设你在用 AI 跑一个长任务,想让进度卡一直挂在 Mac 屏幕右上角:

# 第一步:让 show_widget 生成并托管一个进度 widget,目标指向节点面板
show_widget( presentation.target = "node_panel", props = { ... 进度数据 ... } )
# 返回: /__openclaw__/canvas/documents/abc123

# 第二步:canvas 把它推到面板,并定位到右上角
canvas( action = "present", url = "/__openclaw__/canvas/documents/abc123",
        x = 1200, y = 20, width = 360, height = 240, node = "你的Mac" )

# 任务更新后,直接跳转刷新内容
canvas( action = "navigate", url = "/__openclaw__/canvas/documents/abc123-v2" )

# 干完了,收掉面板
canvas( action = "hide" )

注意上面 url 用的是 show_widget 返回的托管路由,不是你本地随便写的路径——这是最容易踩的坑。

小结

canvas 是 OpenClaw 里一个「把产出推出聊天框、钉到物理屏幕」的能力,核心是 present / hide / navigate 三个动作 + 一台配对的 Mac 节点。真正的内容由 show_widget(target=node_panel)托管生成,canvas 只做呈现控制。记住三点就能少走弯路:先确认 Mac 节点在线、总开关 host.enabled 要开、内容 URL 用 show_widget 返回的托管路由而非自己编的路径。需要让 AI 的东西「一直在你眼前」时,它就是那个对的工具。

扫码关注公众号，获取更多 OpenClaw 实操技巧：

公众号二维码